/**
 *	\file
 *	\brief represents a single element of a list of GroupLabels
 *
 *	\dot
 *		digraph list {
 *			rankdir=LR;
 *			head [shape="record" label="<f0> PgroupLabel|<f1> next"];
 *			middle [shape="record" label="<f0> PgroupLabel|<f1> next"];
 *			tail [shape="record" label="<f0> Pgroupabel|<f1> next"];
 *
 *			l1 [label="ADMIN"];
 *			l2 [label="1"];
 *			l3 [label="STUDENTS"];
 *
 *			head:f1 -> middle:f0;
 *			middle:f1 -> tail:f0;
 *
 *			head:f0 -> l1;
 *			middle:f0 -> l2;
 *			tail:f0 -> l3;
 *		}
 *	\enddot
 *
 *	You can use this object with the header file "utlist.h" (you can download it from https://github.com/troydhanson/uthash/tree/master/src)
 *	to standardized list data structures. Documentation of "utlist.h" is avaiable here: http://troydhanson.github.io/uthash/utlist.html
 *
 * 	\date Sep 12, 2013
 * 	\author koldar
 */

#ifndef IDENTIFIERLIST_H_
#define IDENTIFIERLIST_H_

#include "utlist.h"
#include "Identifier.h"

/**represents a single element of the list
 *
 */
typedef struct IdentifierElement {
	Pidentifier label; //!< points to a GroupLabel element representing the value of this element list
	struct IdentifierElement* next; //!< points to the next GroupLabel list element
} IdentifierElement;

/**points to a list of identifiers
 *
 */
typedef IdentifierElement* IdentifierList;


typedef IdentifierElement** PidentifierList;

/**alias of PgroupLabelList to improve readability of the code
 *
 */
typedef IdentifierElement* PIdentifierElement;

/**initialize correctly a list
 *
 * \pre
 *  \li list must not be already used
 * \post
 *  \li the list is correctly initiliaze
 *
 * @param list the list to be initizialize
 */
void initIdentifierList(PidentifierList list);

/**add an identifier in the current list
 *
 * \pre
 *  \li list must be already initialize with the function initIdentifierList();
 *  \li id must not be NULL;
 * \post
 *  \li id is appended to the end of the list list;
 *
 * @param list the list in which store the id
 * @param id the id to be appended
 */
void addIdentifierInList(PidentifierList list,Pidentifier id);

/**free all the space occupied by the list. The single ids will <b>not</b>
 * be freed because they are probably be stored in the syntax tree.
 *
 * \dot
 * 	digraph idlist {
 * 		subgraph {
 *	 		rankdir="LR";
 * 			A [shape="record" label="<f0>id|<f1>next"];
 * 			B [shape="record" label="<f0>id|<f1>next"];
 * 			C [shape="record" label="<f0>id|<f1>next"];
 * 			D [shape="record" label="<f0>id|<f1>next"];
 * 			A:f1 -> B:f1 -> C:f1 -> D;
 * 		}
 *
 * 		subgraph cluster0 {
 *			label="in syntax tree"
 *			color="lightyellow"
 * 			id1;
 * 			id2;
 * 			id3;
 * 			id4;
 * 		}
 *
 * 		A:f0 -> id1;
 * 		B:f0 -> id2;
 * 		C:f0 -> id3;
 * 		D:f0 -> id4;
 * 	}
 * \enddot
 *
 * \post
 *  \li the memory allocated for the list is successfully freed without freeing the very strings representing  the identifiers
 *
 * @param list the list to be freed
 */
void freeIdentifierList(PidentifierList list);

#endif /* IDENTIFIERLIST_H_ */
